/**
 * 
 */
package com.feib.soeasy.dao;

import java.io.Serializable;
import java.util.List;

/**
 * @title (#)HibernateDao.java<br>
 * @description 操作資料庫的基礎介面<br>
 * @author Jimmy Liu<br>
 * @version 1.0.0 2010/11/25
 * @copyright Far Eastern International Bank Copyright (c) 2010<br>
 * @20101025 create by Jimmy Liu<br>
 */
public interface HibernateDao<T, PK extends Serializable> 
{
    /**
     * Return the entity class find by its primary key value without locking.
     * Same as <code>findById(pk, false)</code>
     * @param pk Primary key value
     * @return
     */
    public T findByPk(PK pk);

    /**
     * Return the entity class find by its primary key value.
     * If lock is true, the returned instance should be locked.
     * 
     * @param pk Primary key value
     * @param lock Impose object/database lock
     * @return
     */
    public T findByPk(PK pk, boolean lock);

    /**
     * Return ALL instances from persistent storage
     * @return
     */
    public List<T> findAll();

    /**
     * Same as <code>findByExample(exampleInstance, true, true, true)</code>
     * @param exampleInstance
     * @return
     */
    public List<T> findByExample(T exampleInstance);

    /**
     * Same as <code>findByExample(exampleInstance, true, true, true, excludeProperties)</code>
     * @param exampleInstance
     * @param excludeProperties
     * @return
     */
    public List<T> findByExample(T exampleInstance, String ... excludeProperties);

    /**
     * Find all matching persistent objects that matches an exampleInstance object.<br>
     * 查詢不會將關連(associations)的Object當作查詢條件
     * 
     * @param exampleInstance
     * @param ignoreCase Ignore case if true
     * @param enableLike Enable like, and matches anywhere if true
     * @param excludeZeroes Do not include zeroed fields if true
     * @param excludeProperties A list of property names to exclude from the exampleInstance
     * @return
     */
    public List<T> findByExample(T exampleInstance, boolean ignoreCase,
                    boolean enableLike, boolean excludeZeroes, String ... excludeProperties);

    /**
     * Save as a new instance if not currently in persistent storage, or, update it otherwise.
     * 
     * @param entity
     * @return
     */
    public T save(T entity);

    /**
     * Delete the persistent instance
     * @param entity
     */
    public void delete(T entity);

    /**
     * Delete by primary key value
     * 
     * @param pk
     */
    public void deleteById(PK pk);
}